fix(OMN-16050): stop the runtime envelope unwrap at the registered input model - #2741

Ticket

OMN-16050 — runtime envelope-unwrap heuristic over-unwraps domain models that declare payload + marker fields.

Root cause

src/omnibase_infra/runtime/auto_wiring/handler_wiring.py unwrapped payload recursively, guarded by a purely structural predicate:

while _is_transport_envelope(candidate):          # payload mapping + any marker key
    candidate = candidate["payload"]

The module asserted the invariant "domain models never declare these keys". That invariant is false. A domain input model that legitimately declares both a payload mapping and a transport-plausible marker (event_type, correlation_id, partition_key, event_id) is structurally identical to a transport envelope, so the runtime unwrapped through it and handed the kernel the caller's inner payload. The kernel-side model_validate then raised, dispatch reported HandlerDispatchFailureError, and the command was DLQ'd — such a node can never be dispatched over the bus at all.

Reproduced against the real published bytes:

RAW KEYS:      ['event_type', 'correlation_id', 'source_tool', 'payload']
EXTRACTED:     dict KEYS ['session_id', 'defect_ab_probe', 'emitted_at']   <- unwrapped twice
EXTRACTED ->   ValidationError: 4 validation errors
               event_type Field required / 3x extra_forbidden

Fix — stop at the registered input model

_extract_dispatch_payload now takes the dispatcher's contract-registered input model and stops the unwrap at a candidate that IS that model. A candidate is claimed only when BOTH hold:

1. Key containment — every key on the candidate is a declared field (or input alias) of the target model. A real transport envelope always carries at least one routing key the domain model does not declare (source_tool, envelope_id, __debug_trace, __bindings, …), so genuine double/triple-wrapped deliveries keep unwrapping through to the domain.
2. Full model_validate — a partial structural coincidence never halts the unwrap short of the domain payload.

The cheap set check runs first, so model_validate executes only for the rare candidate whose keys are entirely owned by the target model.

Why not the alternatives. Restricting the marker set to "transport-only" keys is a denylist: it fixes one model and silently breaks every genuine envelope that carries only event_type/correlation_id. Declaring envelope depth in the contract moves a runtime fact into static config that every producer would have to keep true. This predicate keys on the type the contract already registers, so it needs no new declaration and no per-model special case.

Blast radius — all 8 call sites accounted for

target_model defaults to None, under which the extractor's behaviour is byte-identical to before — the six unchanged sites read correlation/DLQ metadata and have no registered type in scope.

Seams

• _extract_dispatch_payload(envelope, target_model=None) — additive keyword, all existing callers valid unchanged.
• _is_registered_input_payload(candidate, target_model) — new stop predicate; exceptions from any validator are absorbed as "not the model" (it runs on the dispatch hot path).
• _model_declared_wire_keys(model) — lru_cached field-name + alias set.
• _safe_import_event_model_class(ref) — non-fatal resolver used only to hint the extractor.

Test evidence

RED first. With the fix reverted, the new real-manifest gate fails inside the wired callback with the exact production error:

src/omnibase_infra/runtime/auto_wiring/handler_wiring.py:806: in _callback
    dispatch_arg = target_model.model_validate(payload)
E   pydantic_core._pydantic_core.ValidationError: 4 validation errors
E   event_type      Field required
E   session_id      Extra inputs are not permitted
E   defect_ab_probe Extra inputs are not permitted
E   emitted_at      Extra inputs are not permitted

New tests/unit/runtime/auto_wiring/test_omn16050_registered_input_model_unwrap_stop.py (20 tests):

• the production coercion failure, direct and through _make_dispatch_callback on both the def-B and event_model branches;
• the over-unwrap still reproduces with no registered model in scope — isolating the fix to the stop condition, not a shape change;
• genuine single/double/triple-wrapped envelopes still reach the domain, with and without a target model;
• fail-closed predicate: an undeclared key defeats the claim; declared-keys-but-invalid defeats it; an extra="ignore" model cannot claim a real envelope (validation alone would have); a raising field validator reads as "not the model"; wire aliases are claimable.

Runtime Startup CI gate (this PR touches auto_wiring/): tests/integration/test_auto_wiring_real_manifest.py gains test_real_manifest_wiring_preserves_registered_envelope_shaped_input_model, which loads the real contract manifest from disk via discover_contracts(), runs wire_from_manifest with the kernel's argument shape against a real MessageDispatchEngine, asserts zero unexpected failures and that the probe contract reached WIRED (a skipped probe would make the gate vacuous), then invokes the dispatcher the wiring registered with the exact captured bytes and asserts the handler owns an intact registered model whose payload is the caller's payload.

Local gates (all on the .200 runtime):

• uv run ruff format + uv run ruff check src/ tests/ — clean
• uv run mypy src/omnibase_infra/ --strict — Success: no issues found in 2775 source files
• targeted: tests/unit/runtime/ — 5497 passed, 5 skipped
• pre-push governed impacted-test selector escalated to the full suite: 23378 passed, 40 skipped in 577s
• pre-commit run --files <changed> — all hooks pass

Deployment note

Fix is undeployed until the next digest bump; the emitter end-to-end probe re-run belongs to whichever lane performs that bump.

Release identity + tree hygiene (second commit)

v0.38.4 is a published tag, so a packaged-source change on this branch fails the
release-identity gate closed (two code states would otherwise alias under one image
version). Bumped project.version to 0.38.5; scripts/update_version_matrix.py --check
reports the fallback matrix already in sync and
tests/unit/runtime/test_version_compatibility.py passes (25 passed).

Also corrected a single stray SPDX copyright year (2026 -> 2025) in
tests/scripts/test_deploy_runtime_core_contracts_resolution.py. It arrived on dev
already non-compliant and was the lone outlier against 5030 conforming headers, so it
was the only remaining pre-commit run --all-files failure attributable to this tree.
No behaviour change.

Known pre-existing, NOT introduced here: the ARCH-004 imperative-orchestrator ratchet
reports node_runner_fleet_maintain_orchestrator / node_scope_workflow_orchestrator
under --all-files. Neither node is in this diff, both were last touched by earlier
merged PRs, and the hook is in the pre-commit CI skip: list. Flagged, not absorbed.

Runner-image identity rebind (added this round)

runner-image-build-smoke failed closed: shared_env_digest recorded
638933d1c8de12afe5c8024c, recomputed 9a9a74df5af7a1cddd904744.
scripts/ci/ci_env_digest.py's DEFAULT_ENV_INPUTS hashes pyproject.toml and
uv.lock, so the 0.38.5 bump this PR needs for release-identity necessarily
re-keys the shared CI env digest, which re-binds the runner image identity.
Regenerated with scripts/ci/runner_image_identity.py --mode generate
(identity v7 602c1ca4… -> ad3c8a13…); a clean origin/dev worktree passes the
same check, so this is caused by this PR's bump, not pre-existing drift. Every
prior version-bump PR on dev carries the same companion lock update. No
image_version change — base image, Python, uv, runner, gh and kubectl pins are
untouched.

Evidence-Source: OCC#6484
Evidence-Ticket: OMN-16050

Summary by CodeRabbit

• Bug Fixes

  • Improved event dispatch for envelope-shaped inputs, preventing valid domain models from being incorrectly unwrapped.
  • Preserved recursive unwrapping for genuinely nested transport envelopes.
  • Added safer validation and fallback handling when model information is unavailable.

• Tests

  • Added unit and integration coverage for dispatch behavior, model aliases, validation failures, and nested payloads.

• Chores

  • Updated the project version to 0.38.5.
  • Refreshed the runtime runner image lock metadata.